ATOM Documentation

Atom Agent OS: Master Technical Architecture

This document defines the complete technical design of the Atom Agent OS. It covers the intelligence tier, multi-tenant data layer, autonomous execution engine, graduation framework, and delivery model parity between SaaS and Open Source.

---

Architecture Overview

ATOM is a unified platform designed for both human-in-the-loop and fully autonomous agent operations. The following diagram illustrates the interaction between the interface, orchestration, intelligence, and persistence layers.

---

💎 Core Architectural Pillars

1. Unified Intelligence Routing (Meta-Agent)

The **Atom Meta Agent** is the primary driver for all platform interactions. It uses the IntentClassifier to perform real-time classification of intent:

**Three Independent Routing Paths:**

**Intent Classification Process:**

1. User request is analyzed by IntentClassifier.classify_intent()
2. Returns IntentCategory (CHAT/WORKFLOW/TASK) with confidence score
3. For WORKFLOW/TASK: AgentGovernanceService checks agent maturity and certification
4. Graceful degradation: If services unavailable, falls back to CHAT (fail-open)

**Governance Checks:**

• CHAT: Bypasses governance (direct LLM reasoning)
• WORKFLOW: Requires Queen certification (multi-domain 0.85+)
• TASK: Requires Admiral certification (3+ capabilities at AUTONOMOUS)
• Auto-takeover: If governance denies WORKFLOW/TASK, proposes CHAT alternative

1b. Agent Execution Engine (`AgentRunner`)

The **AgentRunner** is the core execution loop that turns plans into actions. It operates on both frontend (Next.js) and backend (FastAPI) with symmetric responsibilities:

The execution loop follows a consistent pattern: **Plan → Context Recall → LLM Reasoning → Governance Gate → Skill Execution → Episode Recording**.

2. Unified LLM Interface (`LLMService`)

LLMService is the **sole entry point** for all LLM interactions across the platform. There is no separate LLMRouter.

> [!NOTE]

> **LLMRouter deprecation (v13.0):** LLMRouter was deprecated in v13.0 and replaced with LLMService. The old LLMRouter is now a 32-line compatibility shim. Use LLMService for all new code.

Internally wraps BYOKHandler for tenant-isolated key management and cognitive tiering (Micro → Standard → Versatile → Heavy → Complex).

3. Delivery Models: SaaS vs. Open Source

The ATOM platform is designed with a "Submodule Parity" philosophy. The core intelligence is identical across both delivery models.

4. Unified Data Ingestion

All data ingestion (Text, Files, Knowledge Graph) follows a unified pipeline shared between SaaS and Open Source:

• **Parsing**: Powered by **Docling** and the PolicyFactExtractor in the atom-upstream core.
• **Enrichment**: Automatic semantic tagging and business fact extraction.
• **Storage**: Ingested facts are stored in **LanceDB** (Reflective Pool) for semantic retrieval and **PostgreSQL** for relational state.
• **Parity**: The only difference is the SaaS layer's **RLS-Isolation** and sub-tenant workspace partitioning.

5. Unified Graduation Framework (AgentGraduationService)

Agents evolve from STUDENT to AUTONOMOUS based on a **4-dimension readiness formula** (not a linear score):

**4-Dimension Matrix (40% Episode + 20% Supervision + 20% Capability + 20% Domain):**

**Detailed Component Breakdown:**

**Dual-Trigger Graduation:**

• **Event-Driven**: After a task completes successfully, report outcome to AgentGraduationService.
• **Periodic Review**: BackgroundRunner performs scheduled system-wide audits every 6 hours via GraduationBackgroundWorker.

**Tenant-Configurable Thresholds:** Graduation criteria are configurable per-tenant with sensible defaults. Tenants can adjust thresholds via AgentGraduationService.CRITERIA configuration.

> [!IMPORTANT]

> **Leadership Certifications**:

> - **Hive Queen**: Requires Multi-Domain expertise + Autonomous maturity. Enables structured blueprint generation.

> - **Fleet Admiral**: Requires Multi-Capability mastery + Autonomous maturity. Enables dynamic multi-specialist recruitment.

6. Recursive Self-Evolution (GEA)

Powered by the **MiniMax M2.7** model, the evolution loop operates as an asynchronous background cycle:

1. **Selection**: Identify top-performing agents for a specific domain.
2. **Synthesis**: Analyze shared traces to extract "Optimal Directives."
3. **Mutation**: Apply directives to agent clones and benchmark.
4. **Graduation**: Successful clones are merged back into the production registry.

---

🚀 Independent Execution Paths

The system satisfies three distinct operational modes:

1. **Direct Real-Time**: Chat requests from the Chat UI hit the Router, which calls LLMService directly for low-latency agent interaction.
2. **Autonomous (Scheduled)**: The BackgroundRunner acts independently, polling the AgentRegistry and triggering agents for maintenance, monitoring, or graduation checks without human intervention.
3. **Coordination (Workflows)**: The Orchestrator manages multi-step, multi-agent pipelines, treating agents as modular "Execution Nodes" within a wider business process.

---

🔌 MCP Tool Protocol

The MCP Service provides a standardized tool projection layer:

• **Tool Discovery**: Semantic search over registered tool schemas.
• **Tool Execution**: Governed execution with audit logging and circuit breaking.
• **Integration Registry**: Centralized dispatch for all integration services (Gmail, Outlook, Jira, Stripe, etc.) via IntegrationRegistry.execute_operation.

---

🔐 Security & Governance

• **Audit Logging**: Every tool execution via AtomMetaAgent is recorded with tenant_id and user_id context.
• **Circuit Breakers**: Multi-agent swarms (Fleets) are automatically throttled if they exceed tenant-level budget (ACU) limits or token rate limits.
• **HITL Verification**: High-risk actions trigger **Human-in-the-loop** (HITL) requests via the Admin UI.
• **Constitutional AI**: Agent actions are validated against Knowledge Graph rules (tax laws, HIPAA, domain-specific constraints).

---

📂 Component Directory

• backend-saas/core/atom_meta_agent.py — Central task routing logic.
• backend-saas/core/llm_service.py — Sole LLM interface, wrapping BYOKHandler.
• src/lib/ai/agent-runner.ts — Frontend agent execution engine (Plan → Execute → Record).
• backend-saas/core/background_agent_runner.py — Backend scheduled/autonomous agent execution.
• src/lib/ai/agent-governance.ts — Frontend action-level governance gating.
• backend-saas/core/agent_governance_service.py — Backend governance service.
• backend-saas/core/agent_graduation_service.py — Unified maturity and certification management.
• backend-saas/core/capability_graduation_service.py — Capability usage thresholds.
• backend-saas/core/domain_aware_graduation_service.py — Domain-specific readiness checks.
• backend-saas/core/agent_fleet_service.py — Dynamic delegation for unstructured tasks.
• backend-saas/core/agents/queen_agent.py — Goal-driven blueprinting.
• backend-saas/core/agent_evolution_loop.py — Recursive self-improvement.
• backend-saas/core/world_model_service.py — Semantic memory for agent learning.
• src/lib/ai/skill-executor.ts — Dynamic skill dispatch (script, API, container, Docker).
• src/lib/ai/skill-registry.ts — Skill registration and discovery.

---

**Architecture Version**: 11.0 (Unified Graduation & LLM Consolidation)

**Last Updated**: April 2026